<html>
<!-- $LastChangedDate: 2010-04-14 13:55:46 -0400 (Wed, 14 Apr 2010) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - World Module</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - World Module</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Overview'>Overview</a></li>
  <li><a href='#Latitude and Longitude'>Latitude and Longitude</a></li>
  <li><a href='#Coordinate Systems'>Coordinate Systems</a></li>
  <li><a href='#World'>World</a></li>
  <li><a href='#Planet'>Planet</a></li>
  <li><a href='#Tangent Matrix'>Tangent Matrix</a></li>
  <li><a href='#Conversion Functions'>Conversion Functions</a></li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Overview'></a>
<h2>Overview</h2>
<p><!--date-->[2010/04]</p>
<p>
The representation of the simulated world is factored into:
</p>
<ul>
  <li>World class (top-level)</li>
  <li>Planet class (flat or spherical)</li>
  <li>Conversion functions (in world::conv namespace)</li>
</ul>
<p>
The World and Planet classes together define the simulated world
but do not contain 3D objects (SceneGraph does).
Planet is a private implementation of the World class.
</p>
<p>
The interface of World was designed for either a flat or spherical world,
and this fact should be kept internal to the World class if possible.
</p>
<p>
The world::conv conversion functions convert between physical metrics,
spherical coordinates, and graphical coordinates.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Latitude and Longitude'></a>
<h2>Latitude and Longitude</h2>
<p><!--date-->[2008/04]</p>
<p>
Latitude defines a <b>semi</b>-circle {0',...,180'}.  lat=0' defines the north pole.
<br>Longitude defines a <b>full</b>-circle {0',...,360'}.  lon=0' defines Greenwich,UK.
</p>
<p>
Most methods have assertions to enforce correct range of both latitude and longitude.
If out-of-range isn't really an error, modulate args using
math::ModuloAbs(180.0f,lat) or (360.0f,lon).
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Coordinate Systems'></a>
<h2>Coordinate Systems</h2>
<p><!--date-->[2008/05]</p>
<ul>
<li>world coordinates</li>
<li>spherical coordinates</li>
<li>physical coordinates</li>
</ul>
<p>
The graphics rendering code is based on <i>world coordinates</i> (<i>object space</i>).
World coordinates are purely a graphical concept.
</p>
<p>
The simulator is designed to start with <i>spherical coordinates</i>.
Spherical coordinates are (latitude,longitude,altitude) (degree,degree,meter).
</p>
<p>
Physical coordinates are (meter,meter,meter).
Data files associated with 3D models define width,length,height in meters.
</p>
<h3>Creation and Conversion of the Coordinate Systems</h3>
<p><!--date-->[2008/05]</p>
<p>
At startup, the simulation maps the Earth's actual measurements
to 3D graphical coordinates (<i>world coordinates</i>).
Once defined, world coordinates and their correlation
to spherical coordinates remain constant.
The simulator may seem to re-orient world space
as the viewpoint moves over the spherical world,
but this is just an illusion.
Rather, the view matrix is recomputed every frame
to be on a tangent (SuperView::ComputeViewMatrix)
which instead changes the mapping world space and eye space.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='World'></a>
<h2>World</h2>
<p><!--date-->[2009/03]</p>
<p>
The C++ World class creates the primordial simulated world
(which is later fully populated by Lua scripts)
and provides info about the world.
</p>
<p>
Palomino-specific: World encapsulates and hides either a <a href='#Planet'>FlatPlanet or SpherePlanet</a>.
</p>
<p><font size='-1'><i>
Historical note:
In previous versions, World was a pager: it created and destroyed Objects as the locus moved.
World served as a fence: it could restrict moving the viewpoint outside the world.
World was complicated with scene-graph functionality and being an Object container,
but that was later factored-out to the
<a href='module_graph.html#SceneGraph'>SceneGraph</a> class.
The World class survives, in part, because some of this functionality may need to be reimplemented.
</font></i></p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Planet'></a>
<h2>Planet</h2>
<p><!--date-->[2008/02]</p>
<p>
Planet is an abstract class whose derivatives are FlatPlanet and SpherePlanet.
Planet is a private implementation of World (World is a Facade over Planet).
</p>
<p>
FlatPlanet defines a single satellite image produced by osgdem (GoldenGate.osga).
Despite being flat, thru Geo, it can be accessed in terms of spherical coordinates.
</p>
<p>
SpherePlanet is a Facade over an <a href='http://www.ossim.org'>OSSIM planet</a>
which can automatically download satellite imagery and
render the entire Earth as an ellipsoid.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Tangent Matrix'></a>
<h2>Tangent Matrix</h2>
<p><!--date-->[2008/02]</p>
<p>
This is a matrix that is tangential to a point on the ellipsoid.
Its Z axis is the "up vector".
The view matrix is transformed thru the tangent matrix
so that the horizon is level (the orientation a human pilot would expect).
The tangent matrix is recomputed as the player moves around the globe.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Conversion'></a>
<a name='Conversion Functions'></a>
<h2>Conversion Functions</h2>
<p><!--date-->[2010/04]</p>
<p>
The world module provides functions to convert between physical and graphical coordinates.
These functions are in the <code>world::conv</code> namespace.
</p>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Wed Apr 14 12:02:47 CDT 2010
<!-- hhmts end -->
</font>
</p>

</body>
</html>
